fix(react-native): capture fatal React render errors - #5293

Problem

React render errors that crash the app no longer reach error tracking on React Native 0.78 and newer.

React 19 (RN 0.78+) reports an uncaught render error through the root onUncaughtError callback, which calls ExceptionsManager.handleException(error, true) directly. It never reaches ErrorUtils, the only hook posthog-react-native uses, so the SDK's fatal capture never runs. On React 18 (RN < 0.78) React rethrew render errors to ErrorUtils, so they were captured.

Reproduced on device, RN 0.86.2 new architecture, Release build:

• Android: the app does not crash. The React host is torn down and the screen goes blank. No $exception is sent.
• iOS: RN raises RCTFatalException and the app aborts. The plugin drops that native report as a duplicate of a JS capture that never happened, so no $exception is sent.

A customer reported this on iOS (RN 0.88-rc, Expo 58, new architecture). Related: #5271 makes iOS keep the native report when JS did not capture the crash.

Changes

• Wrap ExceptionsManager.handleException (optional deep import of react-native/Libraries/Core/ExceptionsManager, feature-detected) so fatal calls go through the same tracker as the ErrorUtils handler. Render fatals then reach handleFatalException, with the same durable native capture and persistence wait as any other fatal. The mechanism stays onuncaughtexception.
• The ErrorUtils hook stays the primary path. If the module is missing or can't be wrapped, only the render path is skipped.
• Non-fatal calls (errors caught by an error boundary) pass straight through.
• One capture per fatal: a handler fatal that RN's default handler forwards to handleException is not captured again. Fatals still being persisted are tracked per error, and a duplicate report of one waits until the original has been forwarded. A forwarded Error is not captured again when the handler PostHog wraps reports it to React Native later (Sentry flushes before calling the handler it replaced).
• Web bundles resolve OptionalReactNativeExceptionsManager.web.ts, which imports nothing, so React Native's ExceptionsManager stays out of the web dependency graph. RN 0.79 and older have no web implementation of Libraries/Utilities/Platform, which it imports.
• No new option. Gated by errorTracking.autocapture.uncaughtExceptions.

Rejected alternatives:

• unstable_setExceptionDecorator: only runs inside reportException, which is skipped when native handles the exception, and it holds a single slot.
• RN$handleException: a read-only global, and handleException calls it anyway.
• console.error: RN logs the error there before reporting it, but it can't tell a fatal render error from one an error boundary caught.

Maintenance risk: if RN moves or stops exporting Libraries/Core/ExceptionsManager, render-crash capture silently stops; handler fatals are unaffected. The module has lived at that path from RN 0.70 through today's nightly (0.89), and RN 0.87 still exports ./Libraries/* after narrowing its exports map. A scheduled contract check against react-native@latest and @nightly is a possible follow-up.

Known gap: on RN 0.78 only, with Metro's non-default experimentalImportSupport: true plus inlineRequires: false, ErrorHandlers caches its named handleException import at startup, so render crashes bypass the wrap there. RN 0.79+ calls ExceptionsManager.handleException through the module object and is covered. Handler fatals are captured in every setup.

Composing with #5271

Both hooks feed one tracker, which calls ErrorTracking.onUncaughtException, where #5271 sets its marker. Whichever merges second needs at most a trivial rebase. With today's plugin, iOS sends one event (JS) because the native report is still dropped unconditionally.

Test plan

• posthog-react-native vitest (77 files, 1347 tests, after merging main), lint, format and typecheck pass. New: test/render-error-capture.spec.ts and test/optional-exceptions-manager.spec.ts. These cover fatal vs non-fatal, dedup, a missing or throwing module, autocapture off, Metro marking the deep import optional, both module shapes, and nothing loading on web.
• Device, Release builds, events checked in a test project. Each cell is the number of $exception events per crash; same-uuid pairs at ingestion are counted once.

• Combined with fix(react-native): stop dropping native crash reports for fatals JS did not see #5271, the setups above give exactly 1 event per crash: the JS event, with the native copy dropped by the marker.
• Sentry row: the crash is thrown from a timer so it reaches ErrorUtils as a fatal, and Sentry's JS handler runs with enableNative: false.
• Web: expo export --platform web, dev and production, passes on Expo 53 (RN 0.79.6) and Expo 57 (RN 0.86.2) with no ExceptionsManager in the bundle; the Expo 53 Android export still bundles it.
• Not verified: RN 0.78 itself (see Known gap), RN's useAlwaysAvailableJSErrorHandling flag on, and Sentry set up after PostHog (that order forwards through RN's default handler synchronously, so the duplicate is skipped).

Release info Sub-libraries affected

Libraries affected

• All of them
• posthog-js (web)
• posthog-js-lite (web lite)
• posthog-node
• posthog-react-native
• @posthog/react-native-plugin
• @posthog/react
• @posthog/ai
• @posthog/convex
• @posthog/next
• @posthog/nextjs-config
• @posthog/nuxt
• @posthog/openfeature-node-provider
• @posthog/openfeature-web-provider
• @posthog/rollup-plugin
• @posthog/webpack-plugin
• @posthog/types
• @posthog/browser-common

Checklist

• Tests for new code
• Accounted for the impact of any changes across different platforms
• Accounted for backwards compatibility of any changes (no breaking changes!)
• Took care not to unnecessarily increase the bundle size

If releasing new changes

• Ran pnpm changeset to generate a changeset file

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

• Claude Code (Claude Opus 5.5) with subagents: shell, file edits, GitHub CLI, the PostHog MCP for reading test events, and Android emulator / iOS simulator runs of examples/example-expo-57.
• Compared the hook options against RN 0.69 to 0.86 and nightly sources and chose the handleException wrap, keeping ErrorUtils as the primary path so a broken deep import can't cost handler fatals. One independent review pass found no blocking issues; it surfaced a dedup memory leak, fixed in the second commit.
• Notes for reviewers: in __DEV__, LogBox's own internal failures can now be captured as fatals. Nothing logs when the deep import is unavailable.

🤖 Generated with Claude Code